postcss-sorting

What is postcss-sorting?

The postcss-sorting npm package is a tool for sorting CSS properties in a specific order. It can be used to enforce a consistent order in CSS files, which can make them more readable and maintainable. It is built as a PostCSS plugin and can be integrated into build processes to automatically sort properties according to a predefined set of rules.

What are postcss-sorting's main functionalities?

Sorting CSS properties

This feature allows developers to automatically sort CSS properties within a stylesheet. The sorting can be customized through options to fit the team's or project's coding standards.

postcss([ require('postcss-sorting')({ /* options */ }) ]).process(css, { from: undefined }).then(result => { console.log(result.css); });

Sorting at-rules

With postcss-sorting, developers can also sort at-rules in a specific order. This can include sorting of media queries, font-face declarations, and other at-rules to improve the structure of the CSS.

postcss([ require('postcss-sorting')({ order: ['custom-properties', 'dollar-variables', 'declarations', 'at-rules', 'rules'] }) ]).process(css, { from: undefined }).then(result => { console.log(result.css); });

Sorting based on custom order

Developers can define a custom order for properties to be sorted. This allows for a highly personalized sorting order that can adhere to specific coding guidelines or preferences.

postcss([ require('postcss-sorting')({ 'properties-order': ['position', 'top', 'right', 'bottom', 'left'] }) ]).process(css, { from: undefined }).then(result => { console.log(result.css); });

Other packages similar to postcss-sorting

stylelint-order

stylelint-order is a plugin for stylelint that checks the order of content within declaration blocks. While it does not automatically sort properties, it can enforce a specific order and report when the order is incorrect.

csscomb

csscomb is a coding style formatter for CSS. Similar to postcss-sorting, it can sort properties according to a specific order. However, csscomb is not a PostCSS plugin and works as a standalone tool or integrated with other code editors.

perfectionist

perfectionist is another PostCSS plugin that beautifies CSS by formatting it according to a consistent standard. It includes sorting capabilities but also focuses on other aspects of beautification, such as indentation and whitespace.

README

PostCSS Sorting

PostCSS plugin to keep rules and at-rules content in order.

Also available as Sublime Text, Atom, VS Code, and Emacs plugin.

Lint and autofix style sheets order with stylelint-order.

Features

• Sorts rules and at-rules content.
• Sorts properties.
• Sorts at-rules by different options.
• Groups properties, custom properties, dollar variables, nested rules, nested at-rules.
• Supports CSS, SCSS (if postcss-scss parser is used), PreCSS and most likely any other syntax added by other PostCSS plugins.

Installation

$ npm install postcss-sorting

Options

The plugin has no default options. Everything is disabled by default.

• order: Specify the order of content within declaration blocks.
• properties-order: Specify the order of properties within declaration blocks.
• unspecified-properties-position: Specify position for properties not specified in properties-order.
• throw-validate-errors: Throw config validation errors instead of just showing and ignoring them.

Handling comments

Comments that are before node and on a separate line linked to that node. Shared-line comments are also linked to that node. Shared-line comments are comments which are located after a node and on the same line as a node.

a {
	top: 5px; /* shared-line comment belongs to `top` */
	/* comment belongs to `bottom` */
	/* comment belongs to `bottom` */
	bottom: 15px; /* shared-line comment belongs to `bottom` */
}

Migration from 2.x

Remove all *-empty-line-before and clean-empty-lines options. Use stylelint with --fix option instead.

properties-order doesn't support property groups. Convert it to simple array. Use stylelint-order with --fix option for empty line before property groups.

Config for 2.x:

{
	"properties-order": [
		{
			"properties": [
				"margin",
				"padding"
			]
		},
		{
			"emptyLineBefore": true,
			"properties": [
				"border",
				"background"
			]
		}
	]
}

Config for 3.x:

{
	"properties-order": [
		"margin",
		"padding",
		"border",
		"background"
	]
}

Usage

See PostCSS docs for examples for your environment.

Text editor

This plugin available as Sublime Text, Atom, VS Code, and Emacs plugin.

Gulp

Add Gulp PostCSS and PostCSS Sorting to your build tool:

npm install gulp-postcss postcss-sorting --save-dev

Enable PostCSS Sorting within your Gulpfile:

var postcss = require('gulp-postcss');
var sorting = require('postcss-sorting');

gulp.task('css', function () {
	return gulp.src('./css/src/*.css').pipe(
		postcss([
			sorting({ /* options */ })
		])
	).pipe(
		gulp.dest('./css/src')
	);
});

Grunt

Add Grunt PostCSS and PostCSS Sorting to your build tool:

npm install grunt-postcss postcss-sorting --save-dev

Enable PostCSS Sorting within your Gruntfile:

grunt.loadNpmTasks('grunt-postcss');

grunt.initConfig({
	postcss: {
		options: {
			processors: [
				require('postcss-sorting')({ /* options */ })
			]
		},
		dist: {
			src: 'css/*.css'
		}
	}
});

Command Line

Add postcss-cli and PostCSS Sorting to your project:

npm install postcss-cli postcss-sorting --save-dev

Create an appropriate postcss.config.js like this example:

module.exports = (ctx) => ({
  plugins: {
    'postcss-sorting': {
      'order': [
        'custom-properties',
        'dollar-variables',
        'declarations',
        'at-rules',
        'rules'
      ],

      'properties-order': 'alphabetical',

      'unspecified-properties-position': 'bottom'
    }
  }
})

Or, simply add the 'postcss-sorting' section to your existing postcss-cli configuration file. Next, execute:

postcss -c postcss.config.js  --no-map -r your_css_file.css

For more information and options, please consult the postcss-cli docs.

Related tools

stylelint and stylelint-order help lint style sheets and let you know if style sheet order is correct. Also, they could autofix style sheets.

Other style sheet formatting tools are Prettier, perfectionist, scssfmt.

Changelog

3.1.0

• Added: throw-validate-errors option.